home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopetemessagehandler.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  7.4 KB  |  226 lines
  1. /*
  2.     kopetemessagehandler.h - Kopete Message Filtering
  3.  
  4.     Copyright (c) 2004      by Richard Smith         <kde@metafoo.co.uk>
  5.     Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
  6.  
  7.     *************************************************************************
  8.     *                                                                       *
  9.     * This library is free software; you can redistribute it and/or         *
  10.     * modify it under the terms of the GNU Lesser General Public            *
  11.     * License as published by the Free Software Foundation; either          *
  12.     * version 2 of the License, or (at your option) any later version.      *
  13.     *                                                                       *
  14.     *************************************************************************
  15. */
  16.  
  17. #ifndef KOPETEMESSAGEHANDLER_H
  18. #define KOPETEMESSAGEHANDLER_H
  19.  
  20. #include <qobject.h>
  21. //#include <kdemacros.h>
  22. #include "kopete_export.h"
  23.  
  24. //FIXME: Message::MessageDirection could be moved into namespace Kopete
  25. // to avoid this being included everywhere
  26. #include "kopetemessage.h"
  27.  
  28. #include <qvaluelist.h>
  29.  
  30. namespace Kopete
  31. {
  32.  
  33. class MessageEvent;
  34. class ChatSession;
  35.  
  36. /**
  37.  * @author Richard Smith       <kde@metafoo.co.uk>
  38.  *
  39.  * An object which sits between the protocol and the chat window which
  40.  * intercepts and processes messages on their way through.
  41.  *
  42.  * This class implements Handler role in the Chain of Responsibility pattern.
  43.  * The Client role will be filled by the Kopete::MessageHandlerChain class.
  44.  */
  45. class KOPETE_EXPORT MessageHandler : public QObject
  46. {
  47.     Q_OBJECT
  48. public:
  49.     MessageHandler();
  50.     virtual ~MessageHandler() = 0;
  51.  
  52.     /**
  53.      * @return the next handler in the chain
  54.      */
  55.     MessageHandler *next();
  56.     // FIXME: remove?
  57.     void setNext( MessageHandler *next );
  58.  
  59.     /**
  60.      * @brief Gets the rich-text capabilities of this message handling object
  61.      *
  62.      * The default implementation returns next()->capabilities().
  63.      */
  64.     virtual int capabilities();
  65.  
  66.     /**
  67.      * @brief Performs any processing necessary on the message
  68.      *
  69.      * @param event The message event to process. Should not be null.
  70.      * 
  71.      * Overriders of this handler @em must cause (possibly asynchronously)
  72.      * one of the following to happen:
  73.      *  - @p event->discard() to be called
  74.      *  - @p event->continue() to be called
  75.      *  - this base class implementation to be called (equivalent to event->continue() but faster)
  76.      * 
  77.      * The base class implementation passes the event on to the next
  78.      * handler in the chain.
  79.      * 
  80.      * @note If you store @p event, be aware that it could be deleted at any time, and either
  81.      *       connect to the its discarded(Kopete::MessageEvent*) signal or store it in a QGuardedPtr.
  82.      */
  83.     virtual void handleMessage( MessageEvent *event );
  84.  
  85.     /** @internal */
  86.     void handleMessageInternal( MessageEvent *event );
  87. private slots:
  88.     /**
  89.      * @internal The message has been accepted. Pass it on to the next handler.
  90.      */
  91.     void messageAccepted( Kopete::MessageEvent *event );
  92.  
  93. private:
  94.     class Private;
  95.     Private *d;
  96. };
  97.  
  98. /**
  99.  * @author Richard Smith       <kde@metafoo.co.uk>
  100.  *
  101.  * A factory for creating MessageHandlers. Instantiate a class derived from MessageHandlerFactory
  102.  * in order to make your MessageHandler be automatically added to the list of handlers used
  103.  * when constructing handler chains.
  104.  * 
  105.  * @note If you construct a handler for an Inbound chain, it may still be asked to process Outbound
  106.  * messages. This is because when a message is being sent it first passes through the Outbound
  107.  * chain to the protocol, then (when it has been delivered) it passes back through the Inbound
  108.  * chain to the chat window to be displayed.
  109.  */
  110. class KOPETE_EXPORT MessageHandlerFactory
  111. {
  112. public:
  113.     /**
  114.      * Constructs a MessageHandlerFactory, and adds it to the list of factories considered when
  115.      * creating a MessageHandlerChain for a ChatSession.
  116.      * 
  117.      * @note Since the factory is added to the list of possible factories before the object is
  118.      * finished being constructed, it is not safe to call any function from a derived class's
  119.      * constructor which may cause a MessageHandlerChain to be created.
  120.      */
  121.     MessageHandlerFactory();
  122.     /**
  123.      * Destroys the MessageHandlerFactory and removes it from the list of factories.
  124.      */
  125.     virtual ~MessageHandlerFactory();
  126.     
  127.     typedef QValueList<MessageHandlerFactory*> FactoryList;
  128.     /**
  129.      * @return the list of registered message handler factories
  130.      */
  131.     static FactoryList messageHandlerFactories();
  132.     
  133.     /**
  134.      * @brief Creates a message handler for a given manager in a given direction.
  135.      * @param manager The manager whose message handler chain the message handler is for
  136.      * @param direction The direction of the chain that is being created.
  137.      * @return the @ref MessageHandler object to put in the chain, or 0 if none is needed.
  138.      */
  139.     virtual MessageHandler *create( ChatSession *manager, Message::MessageDirection direction ) = 0;
  140.     
  141.     /**
  142.      * Special stages usable with any message direction
  143.      */
  144.     enum SpecialStage
  145.     {
  146.         StageDoNotCreate = -10000, ///< do not create a filter for this stage
  147.         StageStart = 0,            ///< start of processing
  148.         StageEnd = 10000           ///< end of processing
  149.     };
  150.     
  151.     /**
  152.      * Processing stages for handlers in inbound message handler chains
  153.      */
  154.     enum InboundStage
  155.     {
  156.         InStageStart = 0,        ///< message was just received
  157.         InStageToSent = 2000,    ///< convert from received format to sent format
  158.         InStageToDesired = 5000, ///< convert to how the user wants the message
  159.         InStageFormat = 7000,    ///< decorate the message without changing the content
  160.         InStageEnd = 10000       ///< message ready for display
  161.     };
  162.     
  163.     /**
  164.      * Processing stages for handlers in outbound message handler chains
  165.      */
  166.     enum OutboundStage
  167.     {
  168.         OutStageStart = 0,        ///< user just hit Send
  169.         OutStageParse = 2000,     ///< process commands
  170.         OutStageToDesired = 4000, ///< convert to how the user wanted to send
  171.         OutStageFormat = 6000,    ///< decorate the message without changing the content
  172.         OutStageToSent = 8000,    ///< convert to the format to send in
  173.         OutStageEnd = 10000       ///< message ready for sending
  174.     };
  175.     
  176.     /**
  177.      * Processing stages for handlers in internal message handler chains
  178.      */
  179.     enum InternalStage
  180.     {
  181.         IntStageStart = 0,  ///< some component just created the message
  182.         IntStageEnd = 10000 ///< message ready for display
  183.     };
  184.     
  185.     /**
  186.      * Offsets within a processing stage. Using these values allows finer
  187.      * control over where in a chain a message handler will be added. Add
  188.      * one of these values to values from the various Stage enumerations
  189.      * to form a filter position.
  190.      */
  191.     enum Offset
  192.     {
  193.         OffsetBefore = -90,
  194.         OffsetVeryEarly = -60,
  195.         OffsetEarly = -30,
  196.         OffsetNormal = 0,
  197.         OffsetLate = 30,
  198.         OffsetVeryLate = 60,
  199.         OffsetAfter = 90
  200.     };
  201.     
  202.     /**
  203.      * @brief Returns the position in the message handler chain to put this factory's handlers
  204.      * @param manager The manager whose message handler chain the message handler is for
  205.      * @param direction The direction of the chain that is being created.
  206.      * @return a member of the InboundStage, OutboundStage or InternalStage enumeration, as
  207.      *         appropriate, optionally combined with a member of the Offset enumeration.
  208.      * @retval StageDoNotCreate No filter should be created for this chain.
  209.      */
  210.     virtual int filterPosition( ChatSession *manager, Message::MessageDirection direction ) = 0;
  211.     
  212. private:
  213.     // noncopyable
  214.     MessageHandlerFactory(const MessageHandlerFactory &);
  215.     void operator=(const MessageHandlerFactory &);
  216.     
  217.     class Private;
  218.     Private *d;
  219. };
  220.  
  221. }
  222.  
  223. #endif
  224.  
  225. // vim: set noet ts=4 sts=4 sw=4:
  226.